Crate atomig

Generic and convenient std atomics.

This crate offers the generic Atomic<T> type which can perform atomic operations on T. There is an important difference to C++'s atomic and the Atomic type from the atomic crate: the Atomic<T> in this crate only works with types that actually support atomic operations on the target platform. A lock-based fallback for other types is not used!

This crate uses the atomic types from std::sync::atomic under the hood and actually does not contain any "interesting" runtime code itself. In other words: this is just a nicer API. Thanks to this, this crate does not use any unsafe code!

Quick example

You can simply use Atomic<T> with all types that implement Atom which are all types that support atomic operations on your platform, but also types that can be represented as the former kind of types (like f32 and char).

use atomig::{Atomic, Ordering};

let a = Atomic::new(true);  // Atomic<bool>
a.store(false, Ordering::SeqCst);

The interface of Atomic very closely matches the interface of the atomic types in std::sync::atomic and you should be able to use this crate as a drop-in replacement. For more examples, see the examples/ folder in the repository.

As you can see in the example, Ordering (from std::sync::atomic) is reexported in this crate for your import convenience.

Traits

This crate contains a number of traits to safely abstract over different atomic types. There are four rather "low level" traits (in the impls module) and three more "high level" ones.

The most important one is probably Atom: to use a type T in Atomic<T>, is has to implement Atom. You can implement that trait for your own types as long as they can be represented by a type that implements impls::PrimitiveAtom. In many cases, you can also simply #[derive(Atom)] for your own types. See Atom's documentation for more information.

Cargo features

This crate has some Cargo features which are disabled by default:

• derive: enables the custom derives for Atom, AtomLogic and AtomInteger. It is disabled by default because it requires compiling a few dependencies for procedural macros.
• serde: enables the serde [Serialize] and [Deserialize] traits on Atomic<T> if T is serializable or deserializable.

Re-exports

pub use std::sync::atomic::Ordering;

Modules

impls

Traits for atomic implementations. You probably do not need to worry about this module.

Structs

Atomic

The main type of this library: a generic atomic type.

Traits

Atom	Types that can be represented by a primitive type supporting atomic operations.
AtomInteger	Atoms for which integer operations on their atomic representation make sense.
AtomLogic	Atoms for which logical operations on their atomic representation make sense.

Derive Macros

Atom	Custom derive for the Atom trait. Please see the trait's documentation for more information on this derive.
AtomInteger	Custom derive for the AtomInteger trait. Please see the trait's documentation for more information on this derive.
AtomLogic	Custom derive for the AtomLogic trait. Please see the trait's documentation for more information on this derive.